home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / ovract.com / OVRACT.DOC next >
Encoding:
Text File  |  1990-01-10  |  5.2 KB  |  111 lines
  1. OVRACT
  2.  
  3. OVRACT is a unit that captures data about the activities of the overlay
  4. manager in a Turbo Pascal 5.x program and saves it in a disk file.
  5. To use it, add the unit OVRACT as near as possible to the beginning of the uses
  6. statement of your main program.  Actually, you can insert it anywhere, but
  7. overlay activity caused by initialization and exit procedures for any units
  8. appearing before OVRACT in the uses statement will not be reported.
  9.  
  10. Compile and run the program normally.  If you are running DOS 3.0 or later, a
  11. file named ProgName.OVD will be produced, where ProgName is the root name of
  12. your EXE file.  Under earlier versions of DOS, a file named OVRACT.OVD is
  13. produced.  This must be renamed ProgName.OVD before running one of the
  14. report programs.
  15.  
  16. For a quick demo, grab the example overlay program that came with your copy
  17. of Turbo Pascal, consisting of the files OVRDEMO.PAS, OVRDEMO1.PAS, and
  18. OVRDEMO2.PAS.  (They're archived in DEMOS.ARC.)  Add OVRACT to the
  19. Uses statement in OVRDEMO and compile to get an EXE file and a MAP file.  Run
  20. OVRDEMO and stop it by pressing any key.  You should now have a file named
  21. OVRDEMO.OVD.  To see a report, type OVRACTM /S /D OVRDEMO.
  22.  
  23.  
  24. OVRACTR and OVRACTM
  25.  
  26. These two programs that produce reports from this data file are also
  27. included.  They are documented in their source files.  They are provided
  28. primarily as examples of how to read the data file and demonstrations of the
  29. kind of information that can be extracted from it.  Hopefully other
  30. programmers will use this data file format to produce more useful utilities.
  31.  
  32.  
  33. File format
  34.  
  35. The format of the overlay activity file was designed to provide as much
  36. information as possible using a minimum of disk space.  Some modifications to
  37. the format to further reduce disk space usage were considered, but at a cost
  38. of complicating the format, which was not considered worth the disk space it
  39. might save.
  40.  
  41. The file is defined as a file of words.  However, it could be read as an
  42. untyped file for fast buffering if desired.  The file starts with a word
  43. containing the file format version number.  Programs using this file format
  44. should check this value in case the format should change in a later version
  45. of this software.  The next word contains the value of the PrefixSeg of the
  46. main program.  This is followed by the "code list," a list of data for all
  47. overlaid units in the program.  For information on specific fields refer to
  48. the pseudo-code below.   The list is terminated by a zero word.  
  49.  
  50. The rest of the file consists of events.  The two types of events are load
  51. and reprieve.  A load event occurs when a call is made to a unit that is not
  52. present in the overlay buffer.  A reprieve event occurs when a call is made
  53. to a unit that is on probation.  The data for either type of event begins
  54. with the event time, expressed as the number of system clocks ticks since the
  55. start of the program.  This is optionally followed by an Overlay Buffer
  56. Change record, which always exists in the first event, and also appears in
  57. any subsequent event when the value of either OvrHeapOrg or OvrHeapEnd has
  58. changed since the previous event.  The next two words give the static segment
  59. address of the unit being loaded or reprieved in this event, and the offset
  60. within that segment of the procedure call that caused this event.  In a load
  61. event this is followed by a the "load list," which is composed of a pair of
  62. words for each unit in the overlay buffer.  The first word of each pair is
  63. the static segment of the unit, and the second word is the segment address
  64. where the unit is loaded in the overlay buffer.  In a reprieve event, there
  65. is no load list since it would be exactly the same as the previous event.  In
  66. either case, the event is terminated by a zero word.   
  67.  
  68.  
  69. Pseudo-code for file format
  70.  
  71.   FileFormatVersion : Word; 
  72.   PrefixSeg : Word;
  73.  
  74.   Code list
  75.     for each overlaid unit in program
  76.       StatSeg : Word;    { static dispatcher segment relative to Prefix+$10 }
  77.       FileOfs : LongInt; { offset of overlay code in OVR file }
  78.       CodeSize : Word;   { size of code in overlay file }
  79.       FixupSize : Word;  { size of transient fixup data }
  80.       EntryPts : Word;   { number of functions and procedures in unit }
  81.     endfor
  82.     EndListMark : Word = 0;
  83.  
  84.   repeat Event
  85.     Time : LongInt       { System clock ticks since start of program }
  86.  
  87.     Overlay buffer change { present only in first event or when limits change }
  88.       OvrHeapMark : Word = $FFFF;
  89.       OvrHeapOrg : Word;
  90.       OvrHeapEnd : Word;
  91.  
  92.     OvrSeg : Word;  { Static segment of unit being loaded or reprieved }
  93.     OvrOfs : Word;  { Offset of procedure call that caused this event }
  94.  
  95.     Load list { not present in reprieve event }
  96.       for each unit loaded in the overlay buffer
  97.         StaticSegment : Word;  { static segment of the unit }
  98.         LoadSegment : Word;    { segment where the unit is loaded in buffer }
  99.       endfor
  100.  
  101.     EndListMark : Word = 0;
  102.   until end of file
  103.  
  104. For further information, please see the file OVRLAY.TXT (CompuServe BPROGA
  105. forum LIB 2).
  106.  
  107. Thanks to the CompuServe BPROGA gang for inspiration, assistance and
  108. encouragement.
  109.  
  110. Ron Schuster [76666,2322]
  111.